fix(cli): guard convention/label-case on a localized label - #16280

Fixes #15880

os lint crashed with a bare TypeError: Cannot read properties of undefined (reading 'toUpperCase') on a config that ObjectStackDefinitionSchema parses clean.

checkLabelCase in packages/cli/src/commands/lint.ts indexed its argument (label[0].toUpperCase()) on a parameter annotated string, while every call site reaches it through any-typed config walking. I18nLabelSchema is z.union([z.string(), InlineLocaleMapSchema]), so on the inline locale map form label[0] is undefined. The throw escaped lintConfig into the command's catch-all: an author who localized an app label or a list-view label could not lint the project at all, on either face, and the message named no rule, no path and no remedy.

The rule now returns early unless typeof label === 'string'. That is the whole change.

Scope: the guard, deliberately not a locale-aware case check

Per triage, the deliverable is that os lint stops crashing — not a decision about how a localized label should be case-checked. Resolving the map and case-checking one entry would decide which locale entry is authoritative for a lint verdict, which is a product call this PR does not make. So the rule says nothing about a localized label, and the tests assert the absence of a convention/label-case issue, so that widening the rule later has to rewrite those assertions on purpose rather than satisfy them silently.

How many call sites reach the rule

lintConfig walks five collections — objects, views, apps, flows, agents — and calls checkLabelCase from 4 sites, reaching 5 authoring paths (getViewLabel resolves to either the list or the listViews.* path):

The sweep filed on the card found exactly two hits because its fixture reached exactly two. The class is the set of call sites, not the set of sweep hits — which is why views[].listViews.*.label is pinned here even though no sweep reached it.

Reachability observation (measured, not fixed here)

I18nLabelSchema is imported by nine ui/ schemas — app, view, page, dashboard, chart, report, action, bulk-action, component — but lintConfig never walks pages, dashboards, charts, reports, actions, bulkActions or components. So convention/label-case never reaches those labels at all, before or after this change. The rule's coverage is narrower than the schema surface it nominally governs. Reported for triage, not touched here.

Both faces, before and after

Fixture: an app with label: { en: 'Todos', 'zh-CN': ... } plus a minimal manifest, driven through the built CLI.

Before (main's lint.ts restored over the fix, CLI rebuilt):

os lint --score           EXIT=1    ✗ Cannot read properties of undefined (reading 'toUpperCase')
os lint --score --json    EXIT=1    {"error":"Cannot read properties of undefined (reading 'toUpperCase')","conversions":[]}

After:

os lint --score           EXIT=0    1 warning(s) · Metadata quality: 97/100  (A)
os lint --score --json    EXIT=0    "passed": true, "score": 97, "grade": "A", no `error` key

What it now says, and that it is true: the linter finishes and reports exactly one warning — protocol/missing-engines-range at manifest.engines.protocol, which is a real property of the fixture and unrelated to the label — with 0 errors, 0 schema and grade A. It emits no convention/label-case issue for the localized label, and it does not report that label as missing either. A guard that merely silenced the crash while emitting a spurious required/label is pinned against explicitly.

Behaviour on a plain string label does not move

Pinned per carrier rather than asserted: all five carriers keep the same warning, message, fix value and path. The ablation below is what proves it — under the mutation those rows stay green, i.e. this branch and main agree on every string carrier.

Ablation

Falsification conditions named and directions predicted before running. Mutation = main's lint.ts restored over the fix; proven on disk by blob hash both ways, restored under an EXIT INT TERM trap with absolute paths, restore proven by observed state.

Mutation proof: source blob d6c14bb15f16... (main) with the guard marker absent, and the marker confirmed absent in dist/ so the CLI ran mutated code. Restore proof: blob back to 611e6613c33b..., git diff HEAD empty, marker present in source and in dist/ again — observed state, not an exit code.

A repair to the pins themselves

The schema-valid block called normalizeStackInput(stack).stack, but normalizeStackInput returns the normalized stack directly, not a wrapper. .stack was undefined, so all four rows were parsing undefined and were red. Its CONTROL row — "a number label does NOT parse, so the parse check discriminates" — was passing for the wrong reason, since undefined does not parse either. The block that exists to prove the localized fixtures are supported authoring input was measuring nothing. Dropping .stack makes the four positives parse clean and leaves the control rejecting, so the control discriminates on the label for the first time.

For triage: a schema asymmetry this PR deliberately did not touch

Measured here, not changed, per the binding instruction not to unify the two declarations in this PR:

• objects[].label (packages/spec/src/data/object.zod.ts:1621) is z.string().optional()
• objects[].fields.*.label (packages/spec/src/data/field.zod.ts:933, FieldSchema) is z.string().optional()
• apps[].label (packages/spec/src/ui/app.zod.ts:1291, AppSchema) is I18nLabelSchema
• views[].list.label (packages/spec/src/ui/view.zod.ts:1819) is I18nLabelSchema.optional()

So an app label may be localized and an object label may not. Narrowing or widening either is a published-declaration change and needs a human floor. Flagged for the dispatching seat to file; not filed from here.

Two anchors above were corrected after review. They were inherited from triage and were pointing at the wrong member; both were re-measured against the tree at this PR's merge base and the citations now name the schema each line actually belongs to.

Both replacements are still I18nLabelSchema and still a plain string respectively, so every conclusion drawn above is unchanged — the accepts-the-map column, the 4-call-site/5-authoring-path count and the asymmetry itself were all driven independently of these line numbers. The one substantive correction is .optional(): with it, both object-side labels are z.string().optional(), so there is no required-vs-optional asymmetry between them. The only asymmetry is plain string vs I18nLabelSchema, which is what #16282 records. The other two anchors (object.zod.ts:1621, view.zod.ts:1819) were re-measured too and are correct as written.

Verification

At head c8d31a3fe0e — the implementation

• pnpm --filter '@objectstack/cli^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/cli exec vitest run over 7 lint/score files — VERDICT command-exit 0, 7 files / 68 tests passed
• pnpm --filter @objectstack/cli typecheck — VERDICT command-exit 0; check:test-typecheck: OK. All three edited files confirmed present in the tsconfig.test.json program via --listFiles, and zero errors in them (the ledger's 3 files / 28 errors are pre-existing and untouched)
• Gate roster: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack — Reconciliation — 57 famil(ies). Targeted subset run locally, all exit 0: check-changeset-no-major, check-empty-changeset, check:nul-bytes, check:test-source-alias, check-changeset-fixed, check:objectui-changeset, check:changeset-gate-self-tests. The farm is CI's to run in full.

At head 764c049adb8 — the changeset level

The first head graded @objectstack/cli patch while declaring clause ②, and Check Changeset refused it. The level is now minor.

That axis is only readable from a pull_request payload, so it is driven here with --event carrying this PR's live label set (documentation, size/m, tests, tooling, needs:contract-review) and its body. Same payload and same --base origin/main in both runs — only the tree differs, by the one word:

CONTROL  --head c8d31a3fe0e  (patch)   EXIT=1
  This PR declares clause-2 YES and grades a package it grew `patch`.
    - @objectstack/cli: patch   ← this PR moves @objectstack/cli's packages/*/src/**

HEAD     (764c049adb8, minor)     EXIT=0
  LEVEL AXIS: this PR declares clause-2 `yes`, and no package whose
  `packages/*/src/**` it moves is graded `patch`.
    carrier: `needs:contract-review` IS on this PR

The control is what makes the green informative: it reproduces the exact CI refusal from the same payload, so the pass is a read axis rather than an unread one.

⚠️ For anyone re-running this: the bare node scripts/check-changeset-no-major.mjs --base origin/main form prints LEVEL AXIS: NOT MEASURED and exits 0 on both trees. It cannot distinguish them, and reading that exit code as a pass is what let the wrong level reach CI. Drive it with --event.

A falsification condition in the test header was also replaced, because it did not falsify. The NO MOVE property offered a label != null guard that changes the empty-string case as a third way to swallow strings. It is neither: on a lowercase string label != null is true, so the row still reports; on '' both spellings reach the falsy label && test and return null. Measured as a pair, mutating lint.ts on disk each way (blob hash before/after, restored under an EXIT INT TERM trap, restore proven by git diff HEAD empty):

The header now names the inverted guard, which produces the observable it claims: every lowercase row stops reporting.

Also at this head, all exit 0: check:nul-bytes, check:changeset-gate-self-tests, check:empty-changeset, check:objectui-changeset, check:changeset-fixed, check:doc-authoring, check-comment-mask-adoption, check-adr-0087-registration --base origin/main, plus the @objectstack/cli dependency-closure build and the package's own build, @objectstack/cli typecheck (check:test-typecheck: OK, the 3-file / 28-error debt ledger unchanged), and the full @objectstack/cli vitest suite — all 270 test files green at this head, measured in two passes: 263 files in the first (3194 passed | 6 expected fail | 31 skipped), and the remaining 7 in a second pass (7 passed, 31 tests). Those 7 drive the PUBLISHED entry and need packages/cli/dist, which the first pass lacked because it had built only the dependency closure (@objectstack/cli^..., which excludes the package itself); they reported packages/cli is not built — a missing prerequisite, not a finding — and pass once the package's own build exists.

Changeset: minor on @objectstack/cli. A bug fix by shape, but the PR declares clause ② and the conformance limb fires — the JSON face moves from {"error": ...} / exit 1 to {"passed": true, ...} / exit 0 on an input class ObjectStackDefinitionSchema parses clean — and a declared widening of a published surface takes at least minor (maintainer ruling, 2026-09-04 decision batch #35).

Generated by Claude Code